Power Programmierung 2

home *** CD-ROM | disk | FTP | other *** search

/ Power Programmierung 2 / Power-Programmierung CD 2 (Tewi)(1994).iso / c / library / dos / communic / serus221 / serious.doc < prev next >

Wrap

Text File | 1990-09-01 | 17.1 KB | 445 lines

page 1 ----------- SERIOUS Users Guide ----------- SERIOUS version 2.21 -- serial communications device driver Copyright (c) 1989,1990 by Norman J. Goldstein 132 Powell Street Vancouver BC Canada V6A 1G1 This software is distributed under the Shareware concept. - You are encouraged to copy and distribute the file SERUS221.ZIP ; in its original, unmodified form only. - No fee is to be charged for the software, other than the actual cost of copying and distribution. - If you end up using SERIOUS , on other than an evaluation basis, you are obliged to send in a registration fee to the copyright owner. The last section of this document has details on this. The copyright owner is not liable for damages of any kind resulting from the use of this software. page 2 Contents Section Page 1 Introduction 3 2 How SERIOUS works 3 3 Function specifications 4 4 Obtaining the entry address 7 5 The inner workings 8 6 Revisions (future and past) 8 7 Registration 9 page 3 Section 1 -- Introduction SERIOUS is a device driver for the serial port of the IBM PC and compatible computers. It is not a communications program. It does provide the tools to write your own communications program. There are, of course, BIOS and DOS routines for serial com- munications, but these are weak, and are not used in serious programs. The SERIOUS device driver is intended to fill this gap. Section 2 -- How SERIOUS works. The program is a DOS installable device driver. The syntax for its entry in the config.sys file is device=serious.sys [name] [ord] The 2 parameters name and ord are optional, and may be placed in any order, separated by at least 1 space. name -- This is the file name by which DOS will recognize the installed driver. The default name is SERIOUS0 . The 1st character must not be a digit. Otherwise, the usual DOS file naming conventions apply; in particular, the name must be at most 8 characters. ord -- The driver may be configured to contain a buffer in which to place incoming characters. The default is that there be no such buffer. If ord is a number between 1 and 16 , then the driver will contain such a buffer. Function 0 (open) of section 3 explains how users may supply their own buffer for the driver to use. The buffer has length 2 to the power of the order. The highest allowable order is 16 , which would give the buffer the size of a complete segment -- 64K bytes. The smallest allowable order is 1 , creating a meagre 2 byte buffer. Two advantages to creating and using a default buffer within the driver are 1) Less work to later open and use the driver, and 2) The buffer remains in RAM even if the application program is terminated; this is a convenient way for the driver to be reaccessed without any incoming characters having been lost, assuming that the terminated program did not close the driver. The disadvantage to creating a default buffer within the driver is that it may not be deallocated. The driver code occupies less than 1300 bytes in RAM; having a 2K buffer would more than double the RAM being used. The driver contains 5 functions, which may be accessed by the applications program. They are described in the next section. page 4 Section 3 -- Function specifications The functions are accessed by the application filling CPU registers with appropriate values, and then performing a far call to the entry address of SERIOUS . The way to obtain the entry address is explained in section 4 . Examples are in the file serface.c , which contains routines for interfacing with Turbo C . These examples also illustrate how to construct an assembler interface to SERIOUS . The file serdemo.c is a Turbo C example of an application using the interface routines of serface.c ; it is a dumb terminal. Every function has the following in common. Input: bx = function number. Returns bx = error code. A value of 0 indicates no error. The file serface.h defines the numeric values of all the error codes. ------------------------------------------------------------------ Function 0: Open Purpose: Inform the driver of the user's configuration, and set up the hardware interrupt routines. Input: bx = 0 . ax = base port number of the serial chip. ch = interrupt request number (IRQ) of the serial chip. cl = order of the user supplied input buffer. es = segment of the user supplied input buffer. di = offset of the user supplied input buffer. The 'order' and purpose of the input buffer is described in section 2 . A reasonable order is 10 , for a buffer of 1K . At 1200 baud, a continuous input stream from the serial port would fill up a 1K buffer in about 10 seconds. A special case is entering a value of 0 for the order. This informs the driver to use the default buffer, which is contained within the driver. The size of this default buffer is determined at installation as a command paramater in the config.sys file, as explained in section 2 . If port is specified as 0 , then this function merely reports whether the driver is currnetly open. No other input information is used, in this case. Return errors: ERR_Active - driver was already open. ERR_BadOrder - the order is not in the allowable range of between 1 and 16 , or neither a default nor a user-defined buffer was specified. ERR_BadIrq - The Interrupt Request number is not between 0 and 15 . ERR_NotActive - this is possible, if port is specified as 0 . ------------------------------------------------------------------ page 5 ------------------------------------------------------------------ Function 1: SetParms Purpose: Set the transmission parameters. Input: bx = 1 . ax = baud. ch = stop , cl = data. dx = parity. baud = rate of transmission, between 2 and 65,535 bits/second. Some common values are 300 , 1200 and 2400 . The driver has been tested at 9600 , using a hardwire connection to a network. data = the number of data bits in each character, between 5 and 8 . Common values are 7 and 8 . stop = the number of stop bits, either 1 or 2 . (Actually, for data of length 5 , only 1 1/2 stop bits are generated when stop is specified as 2 .) parity is the code to specify the type of parity generated. 0,2,4,6: no parity bit. 1: odd parity. 3: even parity. 5: mark parity (Parity bit = 1). 7: space parity (Parity bit = 0). When SERIOUS is opened, the default paramater settings are 1200 baud with 8 data bits, 1 stop bit and no parity. Return errors: ERR_BadData , ERR_BadStop , ERR_BadParity , or ERR_BadBaud indicates the specified parameter is out of range. ------------------------------------------------------------------ ------------------------------------------------------------------ Function 2: Close Purpose: Disable the UART, and restore the hardware interrupt vectors to their values before the previous call to Open . It is important to close SERIOUS before deallocating the input buffer. Otherwise, characters might be written to the old location of the input buffer! Input bx = 2 . Return errors: ERR_NotActive - driver was not open. ------------------------------------------------------------------ page 6 ------------------------------------------------------------------ Function 3: SendChar Purpose: Send a character out through the serial port. Input al = character to be sent. bx = 3 . Return errors: ERR_UARTsleeps - UART is not responding. ------------------------------------------------------------------ ------------------------------------------------------------------ Function 4: RecvChar Purpose: Receive a character from the serial port. Inpput: bx = 4 . Output: ax = the next character (ah=0), if there is one, or ax = -1 , if there is no character. Return errors: none ------------------------------------------------------------------ ------------------------------------------------------------------ Function 5: SetMode Purpose: Specify which interrupts to activate on the UART . Inpput: bx = 5 . al = interrupt mask. A bit is set if the interrupt is to be active. bit 0 -- Received data. 1 -- Transmitter holding register empty. 2 -- Line error. 3 -- Modem status change. The driver routines for reception and transmition require that bits 0 and 1 be set. When the driver is opened, these are the only set bits in the mask. Bits 2 and 3 are useful for debugging. They have the following effect, when the appropriate bit is set. When a line error is detected, the byte ^L is inserted into the input stream, followed by the byte content of the Line Status Register of the UART . The relevant bits of this register are described. Bit Meaning when set: 1 -- Overrun. A received character was overwritten before being read. 2 -- Parity. A wrong parity bit was received. 3 -- Framing. A stop bit was not received where expected. 4 -- Break interrupt. page 7 cont Function 5 -- SetMode When a modem status change is detected, the byte ^S is inserted into the input stream, followed by the byte content of the Modem Status Register of the UART. The bits of this register are described. Bit Meaning when set: 0 -- Change in "Clear To Send" . 1 -- Change in "Data Set Ready" . 2 -- A ring has just completed. 3 -- Change in "Data Carrier Detect" . 4 -- "Clear To Send" . 5 -- "Data Set Ready" . 6 -- Ring indicator. 7 -- "Data Carrier Detect" . When ^L or ^S is being used in this special fashion, and is received through the serial port, the driver preceeds it by the backslash character '\' ; should '\' be received, it too is preceeded by a backslash! In other words, the backslash is used as an escape character, to denote that the next character is to be taken literally. These complications are introduced only if either bits 2 or 3 is set in the interrupt mask; otherwise all characters in the input stream have been actually received through the serial port. Return errors: none ------------------------------------------------------------------ Section 4 -- Obtaining the entry address In the earlier versions of SERIOUS , this was an awkward procedure, as the driver was implemented as a TSR . Not so, any more! The steps outlined in this section are implemented in the function SetEntryAddress() in the file serface.c . The default device name for the driver is SERIOUS0 , although this may be changed at installation, as explained in section 2 . This device must be opened, as any regular file, to obtain a descriptor from DOS . This descriptor is used to perform an "i/o control" read from the driver; this places the entry address into a user supplied variable i.e. into a 4 byte buffer. page 8 Section 5 -- The inner workings The PC serial communications chip is called a UART (Universal Asynchronous Receiver Transmitter). As characters are received by the UART through the serial port, SERIOUS automatically places them into an input buffer (specified by the user), using the hardware interrupt system of the UART. This buffer is implemented as a circular buffer. As soon as wrap-around occurs, the buffer becomes 'empty'. The user must read characters from the input buffer sufficiently often to ensure this does not happen. This is not difficult. A 1K buffer takes about 10 seconds to fill up at 1200 baud. There is plenty of time for the CPU to process the characters. When open, the driver intercepts 3 interrupts: 0Ch -- UART interrupt, mentioned above. 1Ch -- Clock interrupt, for timings. 23h -- DOS break (^C) interrupt. The driver is automatically closed. This means that it is safe, as far as SERIOUS is concerned, to terminate your application using ^C . Section 6 -- Revisions (future and past) Some possible enhancements are: - Allow changing the input buffer. (Now, SERIOUS must first be closed, and then opened to change the size or location of the input buffer.) - Specify/change an output buffer, at any time. This allows for smoother transmission; the interrupt system of the UART would, more completely, handle the sending of characters out through the serial port. (Now, there is no output buffer, and spin waits are used until the UART is ready to send the next character.) - Support the break interrupt facility of the UART. Revision history: This is off to a late start. Better late than never! 23 Aug 1990: Version 2.21 -- Bug fix. Now ports other than COM1 can actually be used. page 9 Section 7 -- Registration Single users are asked to send $20 to the address on the cover page of this document. For evnironments with multiple machines, please contact me to arrange an agreement. In any event, I would like to hear your comments about this software. For registered users, I certainly intend to give detailed responses, as well as early update information. ---------------------------------------------------------------- IBM is a registered trademark of International Business Machines Corporation . Turbo C is a registered trademark of Borland International . I made heavy use of the document "NS16450/INS8250A/NS16C450/INS82C50A Asynchronous Communications Element" , Feb 1985 by National Semiconductor which I obtained, along with other helpful information, from Hamilton Avnet Electronics in Burnaby, BC .